home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / signals.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  12.3 KB  |  347 lines
  1. /**
  2.  * @file signals.h Signal API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _PURPLE_SIGNALS_H_
  26. #define _PURPLE_SIGNALS_H_
  27.  
  28. #include <glib.h>
  29. #include "value.h"
  30.  
  31. #define PURPLE_CALLBACK(func) ((PurpleCallback)func)
  32.  
  33. typedef void (*PurpleCallback)(void);
  34. typedef void (*PurpleSignalMarshalFunc)(PurpleCallback cb, va_list args,
  35.                                       void *data, void **return_val);
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40.  
  41. /**************************************************************************/
  42. /** @name Signal API                                                      */
  43. /**************************************************************************/
  44. /*@{*/
  45.  
  46. /**
  47.  * Signal Connect Priorities
  48.  */
  49. #define PURPLE_SIGNAL_PRIORITY_DEFAULT     0
  50. #define PURPLE_SIGNAL_PRIORITY_HIGHEST  9999
  51. #define PURPLE_SIGNAL_PRIORITY_LOWEST  -9999
  52.  
  53. /**
  54.  * Registers a signal in an instance.
  55.  *
  56.  * @param instance   The instance to register the signal for.
  57.  * @param signal     The signal name.
  58.  * @param marshal    The marshal function.
  59.  * @param ret_value  The return value type, or NULL for no return value.
  60.  * @param num_values The number of values to be passed to the callbacks.
  61.  * @param ...        The values to pass to the callbacks.
  62.  *
  63.  * @return The signal ID local to that instance, or 0 if the signal
  64.  *         couldn't be registered.
  65.  *
  66.  * @see PurpleValue
  67.  */
  68. gulong purple_signal_register(void *instance, const char *signal,
  69.                             PurpleSignalMarshalFunc marshal,
  70.                             PurpleValue *ret_value, int num_values, ...);
  71.  
  72. /**
  73.  * Unregisters a signal in an instance.
  74.  *
  75.  * @param instance The instance to unregister the signal for.
  76.  * @param signal   The signal name.
  77.  */
  78. void purple_signal_unregister(void *instance, const char *signal);
  79.  
  80. /**
  81.  * Unregisters all signals in an instance.
  82.  *
  83.  * @param instance The instance to unregister the signal for.
  84.  */
  85. void purple_signals_unregister_by_instance(void *instance);
  86.  
  87. /**
  88.  * Returns a list of value types used for a signal.
  89.  *
  90.  * @param instance   The instance the signal is registered to.
  91.  * @param signal     The signal.
  92.  * @param ret_value  The return value from the last signal handler.
  93.  * @param num_values The returned number of values.
  94.  * @param values     The returned list of values.
  95.  */
  96. void purple_signal_get_values(void *instance, const char *signal,
  97.                             PurpleValue **ret_value,
  98.                             int *num_values, PurpleValue ***values);
  99.  
  100. /**
  101.  * Connects a signal handler to a signal for a particular object.
  102.  *
  103.  * Take care not to register a handler function twice. Purple will
  104.  * not correct any mistakes for you in this area.
  105.  *
  106.  * @param instance The instance to connect to.
  107.  * @param signal   The name of the signal to connect.
  108.  * @param handle   The handle of the receiver.
  109.  * @param func     The callback function.
  110.  * @param data     The data to pass to the callback function.
  111.  * @param priority The priority with which the handler should be called. Signal handlers are called
  112.  *                 in order from PURPLE_SIGNAL_PRIORITY_LOWEST to PURPLE_SIGNAL_PRIORITY_HIGHEST.
  113.  *
  114.  * @return The signal handler ID.
  115.  *
  116.  * @see purple_signal_disconnect()
  117.  */
  118. gulong purple_signal_connect_priority(void *instance, const char *signal,
  119.                    void *handle, PurpleCallback func, void *data, int priority);
  120.  
  121. /**
  122.  * Connects a signal handler to a signal for a particular object.
  123.  * (priority defaults to 0)
  124.  * 
  125.  * Take care not to register a handler function twice. Purple will
  126.  * not correct any mistakes for you in this area.
  127.  *
  128.  * @param instance The instance to connect to.
  129.  * @param signal   The name of the signal to connect.
  130.  * @param handle   The handle of the receiver.
  131.  * @param func     The callback function.
  132.  * @param data     The data to pass to the callback function.
  133.  *
  134.  * @return The signal handler ID.
  135.  *
  136.  * @see purple_signal_disconnect()
  137.  */
  138. gulong purple_signal_connect(void *instance, const char *signal,
  139.                            void *handle, PurpleCallback func, void *data);
  140.  
  141. /**
  142.  * Connects a signal handler to a signal for a particular object.
  143.  *
  144.  * The signal handler will take a va_args of arguments, instead of
  145.  * individual arguments.
  146.  *
  147.  * Take care not to register a handler function twice. Purple will
  148.  * not correct any mistakes for you in this area.
  149.  *
  150.  * @param instance The instance to connect to.
  151.  * @param signal   The name of the signal to connect.
  152.  * @param handle   The handle of the receiver.
  153.  * @param func     The callback function.
  154.  * @param data     The data to pass to the callback function.
  155.  * @param priority The order in which the signal should be added to the list
  156.  *
  157.  * @return The signal handler ID.
  158.  *
  159.  * @see purple_signal_disconnect()
  160.  */
  161. gulong purple_signal_connect_priority_vargs(void *instance, const char *signal,
  162.                     void *handle, PurpleCallback func, void *data, int priority);
  163.  
  164. /**
  165.  * Connects a signal handler to a signal for a particular object.
  166.  * (priority defaults to 0)
  167.  * The signal handler will take a va_args of arguments, instead of
  168.  * individual arguments.
  169.  *
  170.  * Take care not to register a handler function twice. Purple will
  171.  * not correct any mistakes for you in this area.
  172.  *
  173.  * @param instance The instance to connect to.
  174.  * @param signal   The name of the signal to connect.
  175.  * @param handle   The handle of the receiver.
  176.  * @param func     The callback function.
  177.  * @param data     The data to pass to the callback function.
  178.  *
  179.  * @return The signal handler ID.
  180.  *
  181.  * @see purple_signal_disconnect()
  182.  */
  183. gulong purple_signal_connect_vargs(void *instance, const char *signal,
  184.                                  void *handle, PurpleCallback func, void *data);
  185.  
  186. /**
  187.  * Disconnects a signal handler from a signal on an object.
  188.  *
  189.  * @param instance The instance to disconnect from.
  190.  * @param signal   The name of the signal to disconnect.
  191.  * @param handle   The handle of the receiver.
  192.  * @param func     The registered function to disconnect.
  193.  *
  194.  * @see purple_signal_connect()
  195.  */
  196. void purple_signal_disconnect(void *instance, const char *signal,
  197.                             void *handle, PurpleCallback func);
  198.  
  199. /**
  200.  * Removes all callbacks associated with a receiver handle.
  201.  *
  202.  * @param handle The receiver handle.
  203.  */
  204. void purple_signals_disconnect_by_handle(void *handle);
  205.  
  206. /**
  207.  * Emits a signal.
  208.  *
  209.  * @param instance The instance emitting the signal.
  210.  * @param signal   The signal being emitted.
  211.  *
  212.  * @see purple_signal_connect()
  213.  * @see purple_signal_disconnect()
  214.  */
  215. void purple_signal_emit(void *instance, const char *signal, ...);
  216.  
  217. /**
  218.  * Emits a signal, using a va_list of arguments.
  219.  *
  220.  * @param instance The instance emitting the signal.
  221.  * @param signal   The signal being emitted.
  222.  * @param args     The arguments list.
  223.  *
  224.  * @see purple_signal_connect()
  225.  * @see purple_signal_disconnect()
  226.  */
  227. void purple_signal_emit_vargs(void *instance, const char *signal, va_list args);
  228.  
  229. /**
  230.  * Emits a signal and returns the first non-NULL return value.
  231.  *
  232.  * Further signal handlers are NOT called after a handler returns
  233.  * something other than NULL.
  234.  *
  235.  * @param instance The instance emitting the signal.
  236.  * @param signal   The signal being emitted.
  237.  *
  238.  * @return The first non-NULL return value
  239.  */
  240. void *purple_signal_emit_return_1(void *instance, const char *signal, ...);
  241.  
  242. /**
  243.  * Emits a signal and returns the first non-NULL return value.
  244.  *
  245.  * Further signal handlers are NOT called after a handler returns
  246.  * something other than NULL.
  247.  *
  248.  * @param instance The instance emitting the signal.
  249.  * @param signal   The signal being emitted.
  250.  * @param args     The arguments list.
  251.  *
  252.  * @return The first non-NULL return value
  253.  */
  254. void *purple_signal_emit_vargs_return_1(void *instance, const char *signal,
  255.                                       va_list args);
  256.  
  257. /**
  258.  * Initializes the signals subsystem.
  259.  */
  260. void purple_signals_init(void);
  261.  
  262. /**
  263.  * Uninitializes the signals subsystem.
  264.  */
  265. void purple_signals_uninit(void);
  266.  
  267. /*@}*/
  268.  
  269. /**************************************************************************/
  270. /** @name Marshal Functions                                               */
  271. /**************************************************************************/
  272. /*@{*/
  273.  
  274. void purple_marshal_VOID(
  275.         PurpleCallback cb, va_list args, void *data, void **return_val);
  276. void purple_marshal_VOID__INT(
  277.         PurpleCallback cb, va_list args, void *data, void **return_val);
  278. void purple_marshal_VOID__INT_INT(
  279.         PurpleCallback cb, va_list args, void *data, void **return_val);
  280. void purple_marshal_VOID__POINTER(
  281.         PurpleCallback cb, va_list args, void *data, void **return_val);
  282. void purple_marshal_VOID__POINTER_UINT(
  283.         PurpleCallback cb, va_list args, void *data, void **return_val);
  284. void purple_marshal_VOID__POINTER_INT_INT(
  285.         PurpleCallback cb, va_list args, void *data, void **return_val);
  286. void purple_marshal_VOID__POINTER_POINTER(
  287.         PurpleCallback cb, va_list args, void *data, void **return_val);
  288. void purple_marshal_VOID__POINTER_POINTER_UINT(
  289.         PurpleCallback cb, va_list args, void *data, void **return_val);
  290. void purple_marshal_VOID__POINTER_POINTER_UINT_UINT(
  291.         PurpleCallback cb, va_list args, void *data, void **return_val);
  292. void purple_marshal_VOID__POINTER_POINTER_POINTER(
  293.         PurpleCallback cb, va_list args, void *data, void **return_val);
  294. void purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER(
  295.         PurpleCallback cb, va_list args, void *data, void **return_val);
  296. void purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER_POINTER(
  297.         PurpleCallback cb, va_list args, void *data, void **return_val);
  298. void purple_marshal_VOID__POINTER_POINTER_POINTER_UINT(
  299.         PurpleCallback cb, va_list args, void *data, void **return_val);
  300. void purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER_UINT(
  301.         PurpleCallback cb, va_list args, void *data, void **return_val);
  302. void purple_marshal_VOID__POINTER_POINTER_POINTER_UINT_UINT(
  303.         PurpleCallback cb, va_list args, void *data, void **return_val);
  304.  
  305. void purple_marshal_INT__INT(
  306.         PurpleCallback cb, va_list args, void *data, void **return_val);
  307. void purple_marshal_INT__INT_INT(
  308.         PurpleCallback cb, va_list args, void *data, void **return_val);
  309. void purple_marshal_INT__POINTER_POINTER_POINTER_POINTER_POINTER(
  310.         PurpleCallback cb, va_list args, void *data, void **return_val);
  311.  
  312. void purple_marshal_BOOLEAN__POINTER(
  313.         PurpleCallback cb, va_list args, void *data, void **return_val);
  314. void purple_marshal_BOOLEAN__POINTER_POINTER(
  315.         PurpleCallback cb, va_list args, void *data, void **return_val);
  316. void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER(
  317.         PurpleCallback cb, va_list args, void *data, void **return_val);
  318. void purple_marshal_BOOLEAN__POINTER_POINTER_UINT(
  319.         PurpleCallback cb, va_list args, void *data, void **return_val);
  320. void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_UINT(
  321.         PurpleCallback cb, va_list args, void *data, void **return_val);
  322. void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER(
  323.         PurpleCallback cb, va_list args, void *data, void **return_val);
  324. void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER(
  325.         PurpleCallback cb, va_list args, void *data, void **return_val);
  326.  
  327. void purple_marshal_BOOLEAN__INT_POINTER(
  328.         PurpleCallback cb, va_list args, void *data, void **return_val);
  329.  
  330. void purple_marshal_POINTER__POINTER_INT(
  331.         PurpleCallback cb, va_list args, void *data, void **return_val);
  332. void purple_marshal_POINTER__POINTER_INT64(
  333.         PurpleCallback cb, va_list args, void *data, void **return_val);
  334. void purple_marshal_POINTER__POINTER_INT_BOOLEAN(
  335.         PurpleCallback cb, va_list args, void *data, void **return_val);
  336. void purple_marshal_POINTER__POINTER_INT64_BOOLEAN(
  337.         PurpleCallback cb, va_list args, void *data, void **return_val);
  338. void purple_marshal_POINTER__POINTER_POINTER(
  339.         PurpleCallback cb, va_list args, void *data, void **return_val);
  340. /*@}*/
  341.  
  342. #ifdef __cplusplus
  343. }
  344. #endif
  345.  
  346. #endif /* _PURPLE_SIGNALS_H_ */
  347.